--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
lang/README.zh.md 80d9fd6749c8e6ac8d47f0d9ed8dc4e37fda62e0 (80d9fd67) Text, 14.48 KB
Tc9d1d9# Reticulum MeshChatX
[Tff7b72English](Te6edf3../README.md) | [Tff7b72Deutsch](Te6edf3README.de.md) | [Tff7b72Italiano](Te6edf3README.it.md) | [Tff7b72Русский](Te6edf3README.ru.md) | [Tff7b72日本語](Te6edf3README.ja.md)
Liam Cottle 开发的 Reticulum MeshChat 的一个功能丰富的深度修改分支。
本项目独立于原始 Reticulum MeshChat 项目，与其无关联。
Tff7b72- 网站: [Tff7b72meshchatx.com](Te6edf3https://meshchatx.com)
Tff7b72- 源码: [Tff7b72git.quad4.io/RNS-Things/MeshChatX](Te6edf3https://git.quad4.io/RNS-Things/MeshChatX)
Tff7b72- 官方镜像: [Tff7b72github.com/Quad4-Software/MeshChatX](Te6edf3https://github.com/Quad4-Software/MeshChatX) — 目前亦用于 Windows 与 macOS 构建。
Tff7b72- 发行版: [Tff7b72git.quad4.io/RNS-Things/MeshChatX/releases](Te6edf3https://git.quad4.io/RNS-Things/MeshChatX/releases)
Tff7b72- 变更日志: [Ta5d6ff`CHANGELOG.md`](../CHANGELOG.md)
Tff7b72- TODO: [Tff7b72Boards](Te6edf3https://git.quad4.io/RNS-Things/MeshChatX/projects)
Tc9d1d9## 与 Reticulum MeshChat 的重要差异
Tff7b72- 使用 LXST
Tff7b72- 以原生 SQL 替代 Peewee ORM
Tff7b72- 以原生 Ta5d6ff`fetch` 替代 Axios
Tff7b72- 使用 Electron 41.x（内置 Node 24 运行时）
Tff7b72- Ta5d6ff`.whl` 内置 Web 服务器与前端资源，便于多种部署方式
Tff7b72- i18n
Tff7b72- 使用 PNPM 与 Poetry 管理依赖
Tff7b72> [!WARNING]
Tff7b72> MeshChatX 不保证与旧版 Reticulum MeshChat 的数据兼容。迁移或测试前请备份数据。
Tff7b72> [!WARNING]
Tff7b72> 旧系统尚未完全支持。当前最低要求：Python `>=3.11`，Node `>=24`（Electron 41 与 Node 24 一致；`package.json` 的 `engines` 与 CI 同一基线）。
Tc9d1d9## 系统要求
Tff7b72- Python Ta5d6ff`>=3.11`（来自 Ta5d6ff`pyproject.toml`）
Tff7b72- Node.js Ta5d6ff`>=24`（来自 Ta5d6ff`package.json` 的 Ta5d6ff`engines`）
Tff7b72- pnpm Ta5d6ff`10.33.0`（来自 Ta5d6ff`package.json` 的 Ta5d6ff`packageManager`）
Tff7b72- Poetry（用于 Ta5d6ff`Taskfile.yml` 与 CI 工作流）
Ta5d6ff```Ta5d6ffbash
task install
task lint:all
task test:all
task build:all
Ta5d6ff```
Tc9d1d9## 安装方式
请按运行环境与打包形式选择。
| 方式 | 包含前端 | 架构 | 适用场景 |
| --------------------- | -------- | ---------------------------- | ----------------------------------- |
| Docker 镜像 | 是 | Ta5d6ff`linux/amd64`, Ta5d6ff`linux/arm64` | Linux 服务器快速部署 |
| Python wheel (Ta5d6ff`.whl`) | 是 | 任何 Python 支持的架构 | 无需 Node 构建的无头/Web 服务器安装 |
| Linux AppImage | 是 | Ta5d6ff`x64`, Ta5d6ff`arm64` | 便携式桌面使用 |
| Debian 包 (Ta5d6ff`.deb`) | 是 | Ta5d6ff`x64`, Ta5d6ff`arm64` | Debian/Ubuntu 安装 |
| RPM 包 (Ta5d6ff`.rpm`) | 是 | 取决于 CI | Fedora/RHEL/openSUSE |
| 从源码 | 本地构建 | 主机架构 | 开发与自定义构建 |
说明:
Tff7b72- 发布工作流明确构建 Linux Ta5d6ff`x64` 与 Ta5d6ff`arm64` 的 AppImage + DEB。
Tff7b72- RPM 亦会尝试构建，成功时上传。
Tc9d1d9## 快速开始: Docker
Tff7b72- **Docker Hub:** Ta5d6ff`quad4io/meshchatx`
Tff7b72- **GHCR:** Ta5d6ff`ghcr.io/quad4-software/meshchatx`
Ta5d6ff```Ta5d6ffbash
docker compose up -d
Ta5d6ff```
默认 compose 文件映射:
Tff7b72- 主机 Ta5d6ff`127.0.0.1:8000` -> 容器端口 Ta5d6ff`8000`
Tff7b72- Ta5d6ff`./meshchat-config` -> Ta5d6ff`/config` 持久化
如遇权限问题:
Ta5d6ff```Ta5d6ffbash
sudo chown -R T79c0ff1000:1000 ./meshchat-config
Ta5d6ff```
Tc9d1d9## 从发行版安装
Tc9d1d9### 1) Linux AppImage (x64/arm64)
Tff7b721. 从发行版下载 Ta5d6ff`ReticulumMeshChatX-v<版本>-linux-<架构>.AppImage`。
Tff7b722. 赋予执行权限并运行:
Ta5d6ff```Ta5d6ffbash
chmod +x ./ReticulumMeshChatX-v*-linux-*.AppImage
./ReticulumMeshChatX-v*-linux-*.AppImage
Ta5d6ff```
Tc9d1d9### 2) Debian/Ubuntu `.deb` (x64/arm64)
Tff7b721. 下载 Ta5d6ff`ReticulumMeshChatX-v<版本>-linux-<架构>.deb`。
Tff7b722. 安装:
Ta5d6ff```Ta5d6ffbash
sudo apt install ./ReticulumMeshChatX-v*-linux-*.deb
Ta5d6ff```
Tc9d1d9### 3) RPM 系统
Tff7b721. 若发行版中存在，下载 Ta5d6ff`ReticulumMeshChatX-v<版本>-linux-<架构>.rpm`。
Tff7b722. 安装:
Ta5d6ff```Ta5d6ffbash
sudo rpm -Uvh ./ReticulumMeshChatX-v*-linux-*.rpm
Ta5d6ff```
Tc9d1d9### 4) Python wheel (`.whl`)
发行版 wheel 包含已构建的前端资源。
Ta5d6ff```Ta5d6ffbash
pip install ./reticulum_meshchatx-*-py3-none-any.whl
meshchatx --headless
Ta5d6ff```
亦支持 Ta5d6ff`pipx`:
Ta5d6ff```Ta5d6ffbash
pipx install ./reticulum_meshchatx-*-py3-none-any.whl
Ta5d6ff```
Tc9d1d9## 从源码运行（Web 服务器模式）
在开发或需要本地定制构建时使用。
Ta5d6ff```Ta5d6ffbash
git clone https://git.quad4.io/RNS-Things/MeshChatX.git
Tffa657cd MeshChatX
corepack Tffa657enable
pnpm config Tffa657set verify-store-integrity Tffa657true
pnpm install --frozen-lockfile
pip install Ta5d6ff"poetry==2.3.4"
poetry check --lock
poetry install
pnpm run build-frontend
poetry run python -m meshchatx.meshchat --headless --host T79c0ff127.0.0.1
Ta5d6ff```
关于上述安装命令的说明：
Tff7b72- Ta5d6ff`pnpm install --frozen-lockfile` 禁止更新 Ta5d6ff`pnpm-lock.yaml`，若 lockfile 与 Ta5d6ff`package.json` 不一致则直接失败。这能阻止意外的上游版本被静默安装。
Tff7b72- Ta5d6ff`verify-store-integrity=true` 已在项目的 Ta5d6ff`.npmrc` 中设置；显式的 Ta5d6ff`pnpm config set` 行同时加固用户级配置。
Tff7b72- pnpm v10+ 默认禁用所有生命周期脚本（`preinstall`/`postinstall`）。仅 Ta5d6ff`package.json` 中 Ta5d6ff`pnpm.onlyBuiltDependencies` 列出的包允许执行安装脚本（当前为 Ta5d6ff`electron`、Ta5d6ff`electron-winstaller`、Ta5d6ff`esbuild`、Ta5d6ff`protobufjs`）。
Tff7b72- Ta5d6ff`poetry check --lock` 会在 Ta5d6ff`poetry.lock` 与 Ta5d6ff`pyproject.toml` 不同步时立即失败；随后的 Ta5d6ff`poetry install` 只会从 lock 文件解析依赖。
Tff7b72- 若需严格按 lock 文件安装 Poetry 依赖（不进行隐式刷新），用 Ta5d6ff`pip install "poetry==2.3.4"` 固定 Poetry 版本，与 CI 保持一致。
如果确有意愿更新依赖，请在独立提交中运行 Ta5d6ff`pnpm update` / Ta5d6ff`poetry update`，并在推送前审查生成的 lock 文件 diff。
Tc9d1d9## 在沙盒中运行（Linux）
若要在额外隔离文件系统的情况下运行原生 Ta5d6ff`meshchatx`（别名：`meshchat`），可使用 **Firejail** 或 **Bubblewrap**（Ta5d6ff`bwrap`），同时保留 Reticulum 与 Web 界面所需的网络访问。完整示例（pip/pipx、Poetry、USB 串口说明）见:
Tff7b72- [Ta5d6ff`docs/meshchatx_linux_sandbox.md`](../docs/meshchatx_linux_sandbox.md)
在提供已捆绑或已同步的 Ta5d6ff`meshchatx-docs` 时，应用内 **文档**（MeshChatX 文档）列表亦会显示同一页面。
Tc9d1d9## Linux 桌面：绘文字字体
绘文字选择器使用系统字体（Electron/Chromium）渲染标准 Unicode 绘文字。若显示为空白方框（“豆腐块”），请安装彩色绘文字字体包并重启应用。
| 发行版（示例） | 软件包 |
| -------------------------- | --------------------------------------------------------------------- |
| Arch Linux、Artix、Manjaro | Ta5d6ff`noto-fonts-emoji`（Ta5d6ff`sudo pacman -S noto-fonts-emoji`） |
| Debian、Ubuntu | Ta5d6ff`fonts-noto-color-emoji`（Ta5d6ff`sudo apt install fonts-noto-color-emoji`） |
| Fedora | Ta5d6ff`google-noto-emoji-color-fonts` |
安装后若仍异常，可运行 Ta5d6ff`fc-cache -fv`。可选：最小安装可再装 Ta5d6ff`noto-fonts` 以覆盖更多符号。
Tc9d1d9## 从源码构建桌面包
脚本定义于 Ta5d6ff`package.json` 与 Ta5d6ff`Taskfile.yml`。
Tc9d1d9### Linux x64 AppImage + DEB
Ta5d6ff```Ta5d6ffbash
pnpm run dist:linux-x64
Ta5d6ff```
Tc9d1d9### Linux arm64 AppImage + DEB
Ta5d6ff```Ta5d6ffbash
pnpm run dist:linux-arm64
Ta5d6ff```
Tc9d1d9### RPM
Ta5d6ff```Ta5d6ffbash
pnpm run dist:rpm
Ta5d6ff```
或通过 Task:
Ta5d6ff```Ta5d6ffbash
task dist:fe:rpm
Ta5d6ff```
Tc9d1d9## 架构支持
Tff7b72- Docker 镜像: Ta5d6ff`amd64`, Ta5d6ff`arm64`
Tff7b72- Linux AppImage: Ta5d6ff`x64`, Ta5d6ff`arm64`
Tff7b72- Linux DEB: Ta5d6ff`x64`, Ta5d6ff`arm64`
Tff7b72- Windows: Ta5d6ff`x64`, Ta5d6ff`arm64`（提供构建脚本）
Tff7b72- macOS: 提供构建脚本（`arm64`、`universal`），适用于本地构建环境
Tff7b72- Android: 原生 APK — ABI Ta5d6ff`arm64-v8a`、Ta5d6ff`x86_64` 与 universal
Tc9d1d9## Android
MeshChatX 支持构建原生 Android APK（不仅限于 Termux）。
Tc9d1d9### 从源码构建 APK
在仓库根目录执行:
Ta5d6ff```Ta5d6ffbash
T8b949e# 1) 构建 android/app/build.gradle 所需的 Chaquopy 轮子
bash scripts/build-android-wheels-local.sh
T8b949e# 2) 构建通用 APK（一次 debug + 一次 release；见 android/README.md）
Tffa657cd android
./gradlew --no-daemon :app:assembleDebug :app:assembleRelease
Ta5d6ff```
仅一种 Android 变体（无 Ta5d6ff`slim` / Ta5d6ff`full` flavor）。Gradle 将完整 Ta5d6ff`meshchatx/` 同步到 Ta5d6ff`app/src/main/python/meshchatx/`，含离线仓库 wheel。**ABI 打包：** Ta5d6ff`universal`（默认）或 Ta5d6ff`split`（见 Ta5d6ff`android/app/build.gradle`）。
**`-PmeshchatxAbiPackaging=universal`**（默认）时：
Tff7b72- 调试：`android/app/build/outputs/apk/debug/app-debug.apk`
Tff7b72- 发布：`android/app/build/outputs/apk/release/app-release-unsigned.apk`
说明:
Tff7b72- 发布构建默认未签名（`scripts/sign-android-apks.sh`）。
Tff7b72- ABI：`-PmeshchatxAbis` 或 Ta5d6ff`MESHCHATX_ABIS`；打包：`-PmeshchatxAbiPackaging` 或 Ta5d6ff`MESHCHATX_ABI_PACKAGING`。
Tff7b72- 若仓库根存在 Ta5d6ff`dist/reticulum_meshchatx-*.whl`（例如 Ta5d6ff`python -m build --wheel -o dist .` 后），捆绑时优先使用该 wheel。详见 [Ta5d6ff`android/README.md`](../android/README.md)。
更多文档:
Tff7b72- [Ta5d6ff`docs/meshchatx_on_android_with_termux.md`](../docs/meshchatx_on_android_with_termux.md)
Tff7b72- [Ta5d6ff`android/README.md`](../android/README.md)
Tc9d1d9## 配置
| 参数 | 环境变量 | 默认值 | 说明 |
| -------------------------- | ---------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
| Ta5d6ff`--host` | Ta5d6ff`MESHCHAT_HOST` | Ta5d6ff`127.0.0.1` | Web 服务器绑定地址 |
| Ta5d6ff`--port` | Ta5d6ff`MESHCHAT_PORT` | Ta5d6ff`8000` | Web 服务器端口 |
| Ta5d6ff`--no-https` | Ta5d6ff`MESHCHAT_NO_HTTPS` | Ta5d6ff`false` | 禁用 HTTPS |
| Ta5d6ff`--ssl-cert` / Ta5d6ff`--ssl-key` | Ta5d6ff`MESHCHAT_SSL_CERT` / Ta5d6ff`MESHCHAT_SSL_KEY` | （无） | PEM 证书与私钥路径；需同时设置。覆盖身份下 Ta5d6ff`ssl/` 目录中自动生成的证书。 |
| Ta5d6ff`--rns-log-level` | Ta5d6ff`MESHCHAT_RNS_LOG_LEVEL` | （无） | Reticulum（RNS）日志级别：`none`、`critical`、`error` 等或数值。同时设置时 CLI 优先于环境变量。 |
| Ta5d6ff`--headless` | Ta5d6ff`MESHCHAT_HEADLESS` | Ta5d6ff`false` | 不自动打开浏览器 |
| Ta5d6ff`--auth` | Ta5d6ff`MESHCHAT_AUTH` | Ta5d6ff`false` | 启用基本认证 |
| Ta5d6ff`--storage-dir` | Ta5d6ff`MESHCHAT_STORAGE_DIR` | Ta5d6ff`./storage` | 数据目录 |
| Ta5d6ff`--public-dir` | Ta5d6ff`MESHCHAT_PUBLIC_DIR` | 自动/捆绑 | 前端文件目录（无捆绑资源安装时需要） |
Tc9d1d9## 分支
| 分支 | 用途 |
| -------- | ---------------------------------------- |
| Ta5d6ff`master` | 稳定发布。仅限生产就绪代码。 |
| Ta5d6ff`dev` | 活跃开发。可能包含不稳定或不完整的更改。 |
Tc9d1d9## 开发
Ta5d6ff`Taskfile.yml` 中的常用任务:
Ta5d6ff```Ta5d6ffbash
task install
task lint:all
task test:all
task build:all
Ta5d6ff```
Ta5d6ff`Makefile` 快捷方式:
| 命令 | 说明 |
| -------------- | --------------------------- |
| Ta5d6ff`make install` | 安装 pnpm 与 poetry 依赖 |
| Ta5d6ff`make run` | 通过 poetry 运行 MeshChatX |
| Ta5d6ff`make build` | 构建前端 |
| Ta5d6ff`make lint` | 运行 eslint 与 ruff |
| Ta5d6ff`make test` | 运行前端与后端测试 |
| Ta5d6ff`make clean` | 移除构建产物与 node_modules |
Tc9d1d9## 版本
本仓库当前版本: Ta5d6ff`4.6.0`。
Tff7b72- JavaScript/Electron 版本以 Ta5d6ff`package.json` 为准。
Tff7b72- Ta5d6ff`meshchatx/src/version.py` 通过以下命令与 Ta5d6ff`package.json` 同步:
Ta5d6ff```Ta5d6ffbash
pnpm run version:sync
Ta5d6ff```
发布时请保持相关字段一致（`package.json`、`pyproject.toml`、`meshchatx/__init__.py`）。
Tc9d1d9## 安全
Tff7b72- [Ta5d6ff`SECURITY.md`](../SECURITY.md)
Tff7b72- 应用内置完整性检查与默认 HTTPS/WSS
Tff7b72- CI 与发版在 Ta5d6ff`.github/workflows/`；Gitea 仅保留 Ta5d6ff`.gitea/workflows/github-release-sync.yml` 用于同步 GitHub Release（见 Ta5d6ff`SECURITY.md`）
Tc9d1d9## 添加语言
语言检测是自动的。在 Ta5d6ff`meshchatx/src/frontend/locales/` 下新增 JSON 文件（例如 Ta5d6ff`xx.json`），键与 Ta5d6ff`en.json` 一致，并在顶层设置 Ta5d6ff`_languageName` 作为语言选择器中的显示名称。可以复制 Ta5d6ff`en.json` 后完全人工翻译；**使用 Argos 等机器辅助生成是可选的**，并非必需。
**欢迎提交纠错与人工翻译。** 若修正现有语言文件或提交完整人工翻译，请通过合并请求或议题提交至[项目源码仓库](https://git.quad4.io/RNS-Things/MeshChatX)或 [Tff7b72GitHub 镜像](Te6edf3https://github.com/Quad4-Software/MeshChatX)。
**可选：Argos Translate 初稿** -- 若需要从 Ta5d6ff`en.json` 生成机器翻译初稿，可使用 Ta5d6ff`scripts/argos_translate.py`。它会处理格式并有助于保护插值变量（如 Ta5d6ff`{count}`）。
Ta5d6ff```Ta5d6ffbash
T8b949e# 如果尚未安装，请安装 argostranslate
pip install argostranslate
T8b949e# 运行翻译脚本
python scripts/argos_translate.py --from en --to xx --input meshchatx/src/frontend/locales/en.json --output meshchatx/src/frontend/locales/xx.json --name Ta5d6ff"您的语言名称"
Ta5d6ff```
机器初稿之后，建议由 LLM 或人工审校语法、语境与语气（如正式与非正式）。
运行 Ta5d6ff`pnpm test -- tests/frontend/i18n.test.js --run` 验证与 Ta5d6ff`en.json` 的键一致性。
不需要其他代码更改。应用程序、语言选择器和测试在构建时从 Ta5d6ff`meshchatx/src/frontend/locales/` 目录发现所有语言环境。
Tc9d1d9## 致谢
Tff7b72- [Tff7b72Liam Cottle](Te6edf3https://github.com/liamcottle) - 原始 Reticulum MeshChat
Tff7b72- [Tff7b72RFnexus](Te6edf3https://github.com/RFnexus) - Micron 解析器（JavaScript）
Tff7b72- [Tff7b72markqvist](Te6edf3https://github.com/markqvist) - Reticulum, LXMF, LXST
Tc9d1d9## 许可证
项目自有部分采用 0BSD 许可。
源自 MeshChat 的原始上游部分继续采用 MIT 许可。
完整文本与声明请见 [Ta5d6ff`../LICENSE`](../LICENSE)。
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────